Overview

The goal of internationalization is to allow a single Web application to offer its content and functionality in multiple languages.

You, the Django developer, can accomplish this goal by adding a minimal amount of hooks to your Python code and templates. These hooks are called translation strings. They tell Django: "This text should be translated into the end user's language, if a translation for this text is available in that language."

Django takes care of using these hooks to translate Web apps, on the fly, according to users' language preferences.

Essentially, Django does two things:

• It lets developers and template authors specify which parts of their apps should be translatable.
• It uses these hooks to translate Web apps for particular users according to their language preferences.

How to specify translation strings

Translation strings specify "This text should be translated." These strings can appear in your Python code and templates. It's your responsibility to mark translatable strings; the system can only translate strings it knows about.

def my_view(request):
    output = _("Welcome to my site.")
    return HttpResponse(output)

from django.utils.translation import gettext
def my_view(request):
    output = gettext("Welcome to my site.")
    return HttpResponse(output)

def my_view(request):
    words = ['Welcome', 'to', 'my', 'site.']
    output = _(' '.join(words))
    return HttpResponse(output)

def my_view(request):
    sentence = 'Welcome to my site.'
    output = _(sentence)
    return HttpResponse(output)

def my_view(request, n):
    output = _('%(name)s is my name.') % {'name': n}
    return HttpResponse(output)

from django.utils.translation import gettext_lazy

class MyThing(meta.Model):
    name = meta.CharField(help_text=gettext_lazy('This is the help text'))

from django.utils.translation import gettext_lazy as _

class MyThing(meta.Model):
    name = meta.CharField(help_text=_('This is the help text'))

from django.utils.translation import gettext_lazy as _

class MyThing(meta.Model):
    name = meta.CharField(_('name'), help_text=_('This is the help text'))
    class META:
        verbose_name = _('my thing')
        verbose_name_plural = _('mythings')

from django.utils.translation import ngettext
def hello_world(request, count):
    page = ngettext('there is %(count)d object', 'there are %(count)d objects', count) % {
        'count': count,
    }
    return HttpResponse(page)

<title>{% trans "This is the title." %}</title>

<title>{% trans "value" noop %}</title>

{% blocktrans %}This will have {{ value }} inside.{% endblocktrans %}

{% blocktrans with value|filter as myvar %}
This will have {{ myvar }} inside.
{% endblocktrans %}

{% blocktrans count list|counted as counter %}
There is only one {{ name }} object.
{% plural %}
There are {{ counter }} {{ name }} objects.
{% endblocktrans %}

{% get_current_language as LANGUAGE_CODE %}
{% get_available_languages as LANGUAGES %}

{% some_special_tag _("Page not found") value|yesno:_("yes,no") %}

How to create language files

Once you've tagged your strings for later translation, you need to write (or obtain) the language translations themselves. Here's how that works.

bin/make-messages.py -l de

_("Welcome to my site.")

#: path/to/python/module.py:23
msgid "Welcome to my site."
msgstr ""

make-messages.py -a

bin/compile-messages.py

How Django discovers language preference

Once you've prepared your translations -- or, if you just want to use the translations that come with Django -- you'll just need to activate translation for your app.

Behind the scenes, Django has a very flexible model of deciding which language should be used -- installation-wide, for a particular user, or both.

To set an installation-wide language preference, set LANGUAGE_CODE in your settings file. Django uses this language as the default translation -- the final attempt if no other translator finds a translation.

If all you want to do is run Django with your native language, and a language file is available for your language, all you need to do is set LANGUAGE_CODE.

If you want to let each individual user specify which language he or she prefers, use LocaleMiddleware. LocaleMiddleware enables language selection based on data from the request. It customizes content for each user.

To use LocaleMiddleware, add 'django.middleware.locale.LocaleMiddleware' to your MIDDLEWARE_CLASSES setting. Because middleware order matters, you should follow these guidelines:

• Make sure it's one of the first middlewares installed.
• It should come after SessionMiddleware, because LocaleMiddleware makes use of session data.
• If you use CacheMiddleware, put LocaleMiddleware after it.

For example, your MIDDLEWARE_CLASSES might look like this:

MIDDLEWARE_CLASSES = (
   'django.middleware.sessions.SessionMiddleware',
   'django.middleware.locale.LocaleMiddleware',
   'django.middleware.common.CommonMiddleware',
)

(For more on middleware, see the middleware documentation.)

LocaleMiddleware tries to determine the user's language preference by following this algorithm:

• First, it looks for a django_language key in the the current user's session.
• Failing that, it looks for a cookie called django_language.
• Failing that, it looks at the Accept-Language HTTP header. This header is sent by your browser and tells the server which language(s) you prefer, in order by priority. Django tries each language in the header until it finds one with available translations.
• Failing that, it uses the global LANGUAGE_CODE setting.

Notes:

• In each of these places, the language preference is expected to be in the standard language format, as a string. For example, Brazilian is pt-br.

• If a base language is available but the sublanguage specified is not, Django uses the base language. For example, if a user specifies de-at (Austrian German) but Django only has de available, Django uses de.

• Only languages listed in the LANGUAGES setting can be selected. If you want to restrict the language selection to a subset of provided languages (because your appliaction doesn't provide all those languages), set LANGUAGES to a list of languages. For example:

  LANGUAGES = (
    ('de', _('German')),
    ('en', _('English')),
  )
  

  This example restricts languages that are available for automatic selection to German and English (and any sublanguage, like de-ch or en-us).

Once LocaleMiddleware determines the user's preference, it makes this preference available as request.LANGUAGE_CODE for each request object. Feel free to read this value in your view code. Here's a simple example:

def hello_world(request, count):
    if request.LANGUAGE_CODE == 'de-at':
        return HttpResponse("You prefer to read Austrian German.")
    else:
        return HttpResponse("You prefer to read another language.")

Note that, with static (middleware-less) translation, the language is in settings.LANGUAGE_CODE, while with dynamic (middleware) translation, it's in request.LANGUAGE_CODE.

The set_language redirect view

As a convenience, Django comes with a view, django.views.i18n.set_language, that sets a user's language preference and redirects back to the previous page.

Activate this view by adding the following line to your URLconf:

(r'^i18n/', include('django.conf.urls.i18n')),

(Note that this example makes the view available at /i18n/setlang/.)

The view expects to be called via the GET method, with a language parameter set in the query string. If session support is enabled, the view saves the language choice in the user's session. Otherwise, it saves the language choice in a django_language cookie.

After setting the language choice, Django redirects the user, following this algorithm:

• Django looks for a next parameter in the query string.
• If that doesn't exist, or is empty, Django tries the URL in the Referer header.
• If that's empty -- say, if a user's browser suppresses that header -- then the user will be redirected to / (the site root) as a fallback.

Here's example HTML template code:

<form action="/i18n/setlang/" method="get">
<input name="next" type="hidden" value="/next/page/" />
<select name="language">
{% for lang in LANGUAGES %}
<option value="{{ lang.0 }}">{{ lang.1 }}</option>
{% endfor %}
</select>
<input type="submit" value="Go" />
</form>

Using translations in your own projects

Django looks for translations by following this algorithm:

• First, it looks for a locale directory in the application directory of the view that's being called. If it finds a translation for the selected language, the translation will be installed.
• Next, it looks for a locale directory in the project directory. If it finds a translation, the translation will be installed.
• Finally, it checks the base translation in django/conf/locale.

This way, you can write applications that include their own translations, and you can override base translations in your project path. Or, you can just build a big project out of several apps and put all translations into one big project message file. The choice is yours.

All message file repositories are structured the same way. They are:

• $APPPATH/locale/<language>/LC_MESSAGES/django.(po|mo)
• $PROJECTPATH/locale/<language>/LC_MESSAGES/django.(po|mo)
• All paths listed in LOCALE_PATHS in your settings file are searched in that order for <language>/LC_MESSAGES/django.(po|mo)
• $PYTHONPATH/django/conf/locale/<language>/LC_MESSAGES/django.(po|mo)

To create message files, you use the same make-messages.py tool as with the Django message files. You only need to be in the right place -- in the directory where either the conf/locale (in case of the source tree) or the locale/ (in case of app messages or project messages) directory are located. And you use the same compile-messages.py to produce the binary django.mo files that are used by gettext.

Application message files are a bit complicated to discover -- they need the LocaleMiddleware. If you don't use the middleware, only the Django message files and project message files will be processed.

Finally, you should give some thought to the structure of your translation files. If your applications need to be delivered to other users and will be used in other projects, you might want to use app-specific translations. But using app-specific translations and project translations could produce weird problems with make-messages: make-messages will traverse all directories below the current path and so might put message IDs into the project message file that are already in application message files.

The easiest way out is to store applications that are not part of the project (and so carry their own translations) outside the project tree. That way, make-messages on the project level will only translate strings that are connected to your explicit project and not strings that are distributed independently.

Specialities of Django translation

If you know gettext, you might note these specialities in the way Django does translation:

• The string domain is always django. The string domain is used to differentiate between different programs that store their data in a common message-file library (usually /usr/share/locale/). In Django's case, there are Django-specific locale libraries, so the domain itself isn't used. We could store app message files with different names and put them, say, in the project library, but we decided against this. With message files in the application tree, apps can be distributed more easily.
• Django only uses gettext and gettext_noop. That's because Django always uses DEFAULT_CHARSET strings internally. There isn't much use in using ugettext, because you'll always need to produce utf-8 anyway.
• Django doesn't use xgettext alone. It uses Python wrappers around xgettext and msgfmt. That's mostly for convenience.